⭐ SDOA WHITEPAPER — UNIFIED TECHNICAL & GOVERNANCE EDITION
Version: 5.1 (Unified)
Date: 2026‑06‑18
Classification: Canonical — Architecture & MCP Reference
SECTION 1 — EXECUTIVE SUMMARY
Self‑Describing Object Architecture (SDOA) is a polyglot, sovereign, manifest‑driven architecture in which every module declares its own identity, dependencies, capabilities, documentation, and lifecycle directly inside its own file.

SDOA eliminates:

central configuration files

hidden dependencies

manual registration

global state

cross‑module mutation

ambiguous ownership

spaghetti architecture

SDOA enforces:

sovereignty (every module owns itself)

discoverability (registry auto‑discovers modules)

declarative wiring (manifests replace config files)

three‑layer architecture (L1 features, L2 primitives, L3 adapters/services/workflows)

strict governance (naming, placement, lifecycle, line limits)

polyglot execution (JS, TS, Rust, Python, C++, WASM)

SDOA is the foundation for the SDOA MCP — the Migration & Compliance Pipeline that analyzes, validates, and synthesizes SDOA modules automatically.

SECTION 2 — THE SOVEREIGNTY PRINCIPLE
2.1 Every Module Is a Sovereign
A sovereign module owns:

its own source file(s)

its own manifest

its own CSS (if UI)

its own data files (schemas, configs, catalogs)

its own variants (in variants/)

A sovereign module does not own:

any file in another sovereign’s folder

any global shared directory

any other module’s manifest

2.2 No Cross‑Sovereign Mutation
Modules may not modify each other’s internals.

Allowed communication:

declared dependencies (requires)

EventBus (pub/sub)

StateStore (reactive state)

explicit service calls via registry

Forbidden:

reaching into another module’s folder

modifying another module’s state

monkey‑patching another module

2.3 Variants
Variants are alternate implementations of a sovereign.

Rules:

live in variants/ under the parent

must have full manifest

must declare variant_of

must follow naming rules

SECTION 3 — MANIFEST SPECIFICATION (v1.2 → v5.0)
Every SDOA module must include a manifest at the top of its file.

3.1 Mandatory v1.2 Fields
Code
id
type
version
runtime
capabilities
dependencies
docs
last_modified
3.2 v4.0 Fields
Code
layer
requires
dataFiles
lifecycle
actions {commands, events, accepts, slots}
backendDeps
3.3 v5.0 Fields
Code
operationalRole
optimization {priority, assertionSuite}
3.4 Non‑Compliant Files
If a file cannot be made compliant:

Code
"non-sdoa-compliant": true
This is mandatory for any touched file.

SECTION 4 — THREE‑LAYER ARCHITECTURE
SDOA enforces a strict three‑layer model.

4.1 Layer 1 — Features
compose primitives

load schemas

handle user intent

call adapters

never touch backend directly

never create DOM elements

must follow lifecycle

4.2 Layer 2 — Primitives
render pixels

own their CSS

generic, reusable

no business logic

no backend calls

emit events only

4.3 Layer 3 — Adapters / Services / Workflows / Repositories
IPC

backend calls

state management

persistence

workflow execution

4.4 Layer Traffic Rules
L1 → L2 only

L2 → events only

L3 ← L1 only

no layer skipping

no circular dependencies

SECTION 5 — LIFECYCLE CONTRACTS
5.1 UI Lifecycle (Primitives & Features)
Code
init(config)
mount(container)
update(newState)
unmount()
destroy()
Violations:

DOM work in init

forgetting to remove listeners in unmount

calling destroy without unmount

5.2 Backend Lifecycle (Workflows & Repositories)
Code
init(registry)
run(payload)
dispose()
SECTION 6 — LINE‑LIMIT POLICY (v4.1 Amendment)
Type	Min	Max	Hard	Action
Primitive	150	250	500	split
Feature	200	350	500	extract
Adapter	200	350	500	split
Workflow	200	400	500	extract
Repository	200	400	500	split


Hard limit: never exceed 500 lines.

SECTION 7 — DIRECTORY PLACEMENT RULES
7.1 Canonical Structure
Code
ui/
substrate/
evolution/
authorities/
environment/
documentation/
7.2 Prohibited Directories
Never create:

Code
/assets/
/static/
/deps/
/resources/
/misc/
/global/
7.3 File Routing Rules
CSS → UI sovereign

binaries → engine/substrate

JSON → sovereign that consumes it

scripts → environment

Rust → engine/service

Python → workflow/engine

SECTION 8 — NAMING RULES
Type	File Suffix
Primitive	PascalCase.prim.js
Feature	PascalCase.feature.js
Adapter	PascalCase.adapter.js
Service	PascalCase.service.js
Workflow	PascalCase.workflow.js
Repository	PascalCase.repository.js
Schema	kebab-case.schema.json


Variant naming:

Code
Parent.variant.type.js
Module ID:

Code
Name.type
Name.type.variant
SECTION 9 — ACTION SURFACE (v3.0 → v5.0)
Defines:

commands

events

accepts

slots

workflows

This enables:

auto‑generated command maps

auto‑generated event graphs

auto‑generated workflow graphs

AI‑safe orchestration

SECTION 10 — EVENTBUS SPECIFICATION
API:

Code
emit(event, payload)
on(event, handler)
Rules:

register in init

unregister in destroy

event names: module:action

SECTION 11 — STATESTORE SPECIFICATION
API:

Code
get(key)
set(key, value)
watch(key, handler)
Rules:

no global variables

watch in init, unwatch in destroy

features call primitives.update()

SECTION 12 — BACKEND ROUTING
BackendConnector:

reads backendDeps

builds routing table

dispatches automatically

workflows discovered dynamically

Standard response:

Code
{ ok: true, data: {...} }
{ ok: false, error: "..." }
SECTION 13 — PRIMITIVE CATALOG
19 canonical primitives (Button, Input, Toggle, Panel, Modal, etc.)

These define the UI vocabulary.

SECTION 14 — VARIANT POLICY
Variants:

live in variants/

must have full manifest

must declare variant_of

must follow naming rules

SECTION 15 — DEDUPLICATION POLICY
same name + same extension → variant

same name + same extension + same size → duplicate

duplicates removed

variants moved to variants/

SECTION 16 — AMENDMENT PROCESS
Rules:

amendments must be formal

no one‑off exceptions

version increments follow rules

ratification must be recorded

⭐ SECTION 17 — MODULES VS RULES (THE CRITICAL DISTINCTION)
17.1 Rules
Rules define:

sovereignty

manifests

naming

placement

lifecycle

line limits

action surface

directory structure

deduplication

variant policy

Rules are language‑agnostic.
Rules live in the canonical library.

17.2 Modules
Modules are:

primitives

features

adapters

services

workflows

repositories

engines

Modules are language‑specific.
Modules live in the SDOA application, not the canonical library.

17.3 Exemplars
Some modules are so perfectly compliant that they serve as reference implementations.

These go into:

Code
server/core/sdoa/exemplars/
They are not rules.
They are not constraints.
They are proof.

⭐ SECTION 18 — CANONICAL LIBRARY STRUCTURE (FOR MCP)
Code
server/core/sdoa/
   manifests/
   sovereignty/
   constraints/
   registry/
   version/
   exemplars/
This is the constitution of SDOA.